ETC5513: Collaborative and Reproducible Practices

Tutorial 4

Author

Michael Lydeamore

Published

7 May 2024

🎯 Objectives

  • Create repositories and syncrhonize them between your local and remote repos
  • Create a Quarto report with a tabell, figures and sections that are labelled and referenced
  • Create branches in local and remote repositories
  • Deal with merge conflicts

Exercise 1: Create a new repository (repo) in GitHub

  1. Log in into your GitHub account following this link.

  2. Create a new repo called Tutorial4 and initialize it with a README.md file.

  1. Clone this repository in your local computer. Please make sure that you have Git and GitHub configured in your computer. You should have done this in your Week 3 tutorial.

  1. Open in Rstudio the file README.md, delete any text that is inside the file. Using markdown language please add a heading with title “This is tutorial 4”.

  2. Using your command line interface/Terminal or Git Bash Shell, Stage, commit and push the changes to the remote repository into GitHub. Do not use the Terminal inside Rstudio!

git add README.md
git commit -m "Updating README"
git push origin master
  1. In the same file README.md inside the heading that you created in (5) add the following sentence “In this tutorial we are learning to create and merge branches as well as including the untracked files into our local repo”.

  2. Stage, commit and push the changes to the remote repository in GitHub (this time you shouldn’t have to input your GitHub login details).

git add README.md
git commit -m "Updating README"
git push origin master
  1. Go to GitHub and confirm that you have three commits in your repo history.

  1. Create a file called Tutorial4.qmd that contains the following and install all the required packages:
    • Title: Learning to reference figures, tables and sections
    • Author: Write your name
    • Date information
    • The file will render to html
    • Include the following in the YAML (and delete any other constant that might be in the file):
  2. Using your command line interface/Terminal or Git Bash Shell, stage, commit and push the changes to the remote repo in GitHub.
git add Tutorial4.qmd
git commit -m "Adding quarto file"
git push origin master
  1. Go to GitHub and inspect your commits in the remote repo.

Create a new branch in our local repository

  1. Continue working in the same project as in the previous exercise.

  2. Use the Terminal create a new branch. Please make sure you are in main.
    Hint: git branch

git branch

* master
  1. Follow the workflow that you learned during the lecture to create a new branch using the command line interface/terminal. Call the new branch Feature. You should now be on branch Feature. hint: Use git checkout -b branchname and/or git branch and git checkout.

git checkout -b Feature

or

git branch Feature

git checkout Feature

  1. Refresh your Rstudio to clearly reflect in which branch you are currently working.

  2. Move from this new branch called Feature to main and back to Feature.

git branch
git checkout master
git checkout Feature
  1. Move to Feature and delete Feature from your local repository. Is this branch local or it is remote?

You cannot delete a branch if your repo HEAD is on that branch. Here, you can’t delete Feature because your HEAD is in Feature.

If you have created the branch as described in (5) then the Feature branch is only local, because it hasn’t been committed and pushed.

If you created the branch in RStudio then the branch will also be in the remote repo.

  1. You cannot be in the branch that you want to delete. Move into the main branch and then delete Feature.
git checkout master
git push origin --delete Feature
  1. Create Feature locally again, move into that branch and push the branch into the remote repo in GitHub.
    Hint:
  • git add . (like this we are adding all the modified files into the staging area)
  • git commit -m "Updating Feature"
  • git push origin Feature
  1. Double check in GitHub to see that the branch is now also created in the remote repo. You should now have two branches.

  1. Go back to your Rstudio, open the README.md file and add a new sentence “We are going to create branches using the terminal”.

  2. Using the terminal add these changes into the remote repository as follows:

  • git add . (like this we are adding all the modified files into the staging area)
  • git commit -m "Updating Feature"
  • git push origin Feature
  1. Go back to main, open Tutorial4.qmd and create global options for the figures in the file so that the figures in your report are aligned in the center. Save the changes in the file.

git checkout main

Then, inside Tutorial4.qmd:

```{r}
knitr::opts_chunk$set(fig.align="center")
```
  1. Insert a new R code chuck and load the library tidyverse.]

library(tidyverse)

  1. Continue editing Tutorial4.Rmd and now create a new heading with title: Learning to reference figures.

Inside Tutorial4.qmd

# Learning to reference figures
  1. Inside an R chunk called Figref create 100 values generated from a normal distribution and store them in a variable called x. Create a sequence of values going from 1 to 100 and store them in y. The create a data frame and produce a line plot as follows:

To give a name to the R code chunk, write:

{r Figref}
  1. Continue working on Tutorial4.qmd. Add a caption inside the R code chuck saying “This is random noise”.

Add the chunk option:

#| fig-cap: "This is random noise"
  1. Write a sentence after the plot and reference this figure.

Example solution:

@fig-randomnoise shows an example plot of random noise.

You will need to add label: fig-randomnoise to the chunk producing the plot.

  1. Add a new heading with title “Learning to reference tables”.

  2. Create a table using the first 5 lines of the data frame dat.

```{r}
#| label: tbl-example
#| tbl-cap: "First 5 rows of the example data."

kableExtra::kable(dat[1:5,])
```
  1. Add in a sentence in the text and reference the table.

@tbl-example shows the first few rows of the example table.

  1. Using the command line interface/terminal/Git Bash Shell, stage, commit and push the changes to main:
  • git add tutorial4.Rmd
  • git commit -m "Updating tutorial4.Rmd in main"
  • git push origin main
  • Go to GitHub and verify the new branch has been pushed
  • You might have to hit the refresh button
  1. Refresh Rstudio and go to the diff window. There, select history and display all branches. Your main branch should now be ahead of your Feature branch in the diagram:

  1. Using the terminal you can merge your Feature branch with main branch. Inspect in the diff window if both branches are now merged. Remember you need to move to the branch where we want to include the changes, in this case main:

Hint: git merge Feature -m "Merging branches"

git branch
git checkout master
git merge Feature -m "Merging branches"
git push origin master
  1. Go and inspect the diff window in Rtudio. Now both branches should be merged.

  2. To do at home: You can also create and changing branches directly using the Rstudio GUI interface. Repeat this exercise at home using Rstudio instead of the terminal. When you create the branch as follows the branch gets also updated in the remote repo in GitHub.

Branching and merging conflicts

  1. Your GitHub repository should contain the files README.md and Tutorial4.qmd.
  2. Check the history of your commits and check that your branch is merged to main branch.
  3. Create a conflict: Inside Rstudio open the README.md file and change the first heading “This is tutorial 4” to “I am creating a conflict”
  4. Create a commit for this change with message “Conflict1”. DO NOT PUSH the commit yet.
  5. Select the changes you want to commit and click stage selection. Add a commit message and click Commit. Do NOT push (yet).
  6. Update your README.md on GitHub directly. At the same location in the README.md where you wrote the sentence “I am creating a conflict part 2” in your local repo, now add the following sentence “I have two conflicting versions”.

  1. Now go to Rstudio and push your commit (you can simple click on Push on the top left pane - You don’t need to click to commit cause you have already done it before.
  2. You will get an error message as follows.

  1. Open README.md in RStudio and fix the conflicts: Remove both sentences and add a new one instead that says “I have learned to create and fix a conflict!”.

To resolve the conflict, remove all the conflict markers and save the file:

 /* code unaffected by conflict */
<<<<<<< HEAD
/* code from master that caused conflict */
=======
/* code from feature that caused conflict */
  1. Commit the changes.
git add README.md
git commit -m "Resolving merge conflict"
  1. Push the repo to GitHub.

git push origin master

Extra exercise

  • Go over the referencing project that was covered in the lecture this week (you can find it in the Moodle site).
  • Make sure you fully understand how to reference figures, tables and sections by going over the qmd file.
  • You might create a new GitHub repository and add this project there so that you can keep practicing what it was covered in the tutorial today!